Summary

• bypass the generic records-to-Arrow-to-records round trip in AsyncpgDriver.load_from_records()
• validate and normalize mapping or positional records directly into ordered tuples for one binary COPY call
• share safe quoted and schema-qualified COPY target handling between record and Arrow ingestion
• retain the existing Arrow coercion and row conversion path for actual Arrow inputs
• document the AsyncPG-specific direct-record path and add a conditional COPY-versus-executemany() crossover benchmark

Root cause

The generic load_from_records() implementation materialized every in-memory batch as a PyArrow table. AsyncPG's native Arrow ingest implementation then converted that table back into Python row tuples before calling copy_records_to_table(). The redundant conversion imposed fixed overhead that dominated small and medium record batches.

Behavior

Direct AsyncPG record loads now preserve explicit column order or the first mapping's key order, validate the full batch before truncating or copying, and retain native JSON/JSONB mappings, arrays, UUIDs, and nulls. Empty batches, mixed row shapes, inconsistent mapping keys, missing positional columns, and row-width mismatches fail before database I/O.

Record batches execute exactly one copy_records_to_table() call. Returned jobs report the original destination, format="records", exact rows_processed, and bytes_processed=0. The inherited CockroachDB driver uses the same implementation without changing its advertised capabilities.

Benchmark

The conditional real-PostgreSQL benchmark uses one session and table, three warmups, truncation outside timed sections, and 15 timed samples per variant. Median results from the local PostgreSQL service were:

Closes #664